---------------------------------------------------
LROC WAC EDR IMG Preview and Stack Utility (v1.6.1)
---------------------------------------------------
(revised 2010 Sep 19)

-------
Purpose
-------

The WAC_Previewer is a Windows executable, written in the Delphi 6 dialect of Pascal, can be used to view and stack most EDR (Engineering Data Record) versions of the WAC (Wide Angle Camera) images distributed by the LROC (Lunar Reconnaissance Orbiter Camera) team in 8-bit IMG format over NASA's PDS (Planetary Data Service) system.

The monochrome WAC images, designated by filenames ending in "ME" when in EDR format, consist of a time series of 14x1024 images of the Moon taken with a 1.2 mm aperture camera, and through a single color filter, as the LRO spacecraft drifts over the lunar surface.  They are presented with the first "framelet" of the series shown at the top, proceeding to the last at the bottom, with no spaces between them.  Depending on the spacecraft orientation, the camera sensor may be inverted relative to the drift direction, making the sequence appear as a confusing jumble.

There are three other WAC EDR formats consisting of similar sequences of smaller framelets taken nearly simultaneous in five visible (14x704 pixels each) and/or two ultraviolet wavelength bands (4x128 pixels each -- representing the Moon at roughly 1/5th the scale of the visible light images).  

The present program, inspired by the work of John Moore and Rick Evans (see References, blow), allows the raw framelets to be inverted, when necessary, to make the sequence more visually appealing; and also to overlay (or stack) the successive framelets (or bands) based on an assumed drift (or offset) between frames, to give a continuous mosaic.  When the vertical drift is less than a full band height, the procedure used here is equivalent to laying the band from the second framelet on top of the band from the first (covering its last few pixels), then laying the band from third framelet on top of the second, and so on, until the band from the final framelet is displayed in full.

The program is intended primarily for rapid visualization of the data sets, and should not be expected to give geometrically accurate results.  No attempt is made to correct for distortion in the framelets or for the differing viewpoint of successive framelets.

It runs only on Windows-compatible PC's.


---------------
Sources of Data
---------------

WAC EDR IMG files are posted to the internet by the LROC science team at Arizona State University (ASU).  The raw data sets must be downloaded to disk before they can be opened with the present program.

Raw IMG files can be retrieved with ASU's WMS Browser:

  http://wms.lroc.asu.edu/lroc

or with their Image Search Engine:

  http://wms.lroc.asu.edu/lroc/search

or by drilling down directly through the PDS archive:

  http://lroc.sese.asu.edu/data/

looking for DATA, then COM (commissioning phase) or MAP (mapping phase), then a specific date, then WAC.

The files that can be opened with the present program are those that end in ****E.IMG (= EDR in IMG format).  The four specific kinds the utility recognizes are:

  ***ME.IMG : sequential 14x1024 pixel monochrome data
  ***VE.IMG : sequential visible light color data, each "exposure" consisting of five 14x704 pixel monochrome panels
  ***UE.IMG : sequential ultraviolet light color data, each "exposure" consisting of two 4x128 pixel monochrome panels
  ***CE.IMG : sequential full color data, each "exposure" consisting of the 2 UV data panels described above, followed by the 5 VIS panels.

The identity of the filters used, as well as the date and time of the image, and a table of the range of sensor counts corresponding to each of the 256 intensity levels, can be found in the header text, which can be displayed by the present program. Additional information about the files, including the spacecraft position, altitude and longitude/latitude of the image corners can be found by entering the filename (without the .IMG extension) in the Image Search Engine or by using the =Support= button in the present program.

Using the =Support= button requires downloading to disk the large "CUMINDEX.TAB" text file which is currently found in the following PDS directory:

  http://lroc.sese.asu.edu/data/LRO-L-LROC-2-EDR-V1.0/LROLRC_0002/INDEX/

The related file "CUMINDEX.LBL" explains its format and contents.  Note that you need the index from the "EDR" subset of the PDS release ("LRO-L-LROC-2-EDR-V1.0"). "LROLRC_0002" is the latest volume as of this writing.  As additional volumes are released, the most complete and up-to-date cumulative index will presumably be found in the INDEX directory of most recent EDR volume.  The downloaded file can be placed anywhere on your hard drive. WAC Previewer will first look for it in the folder containing the program itself (the executable file), but if cannot be found there, you will be given the option to browse for it. "CUMINDEX.TAB" is also required to generate automatic LTVT calibrations.


--------------------
Function of Controls
--------------------

==Load==

Click this button to select the downloaded IMG file you want to view.  For monochrome WAC images, the IMG files consist of a series of rows of data, each of which contains 1024 or 704 bytes of data.  The first several rows are an ASCII text header, the remainder are the image matrix.  The file name and number of rows it contains (based on the header text) will appear in the memo box to the right, as well as a description of the band structure and the listed wavelength(s).  The =Raw= button will be automatically clicked to display the image using the current framelet inversion option.  Error messages are generated if the file size does not match that expected from the header.

==Header==

Click this button if you want to view the full header information.  It gives, among many other things, the date and time range during which the data were acquired, the number of milliseconds between exposures, and the spectral bands represented in the IMG, but does not identify the part of the Moon being imaged.

==Support==

Clicking this button reads the large PDS index file CUMINDEX.TAB (see "Sources of Data" above), compiled by the LROC team, and displays selected support data relevant to the current raw data.  This data, including the spacecraft and image positions on the Moon, identifies the region shown and viewpoint, and can be used to "calibrate" the image for display with the Lunar Terminator Visualization Tool (LTVT). Some of it, such as the image start and end times is redundant with information encoded in the IMG header, and should agree with it.  If CUMINDEX.TAB does not exist in the current directory, you will be prompted to browse for it.  Since CUMINDEX.TAB is a large file, locating the support data may take several seconds.

==Correct distortion==
Checking this box tells the software to attempt to correct the raw image data into the geometry that would be expected if the Moon had been photographed from the same viewpoint with an ideal distortion-free camera having the same pixel scale at the center.  The correction is based on the distortion equation given in Robinson (2010), in which it is said that radial distances from the optical center are reduced in the proportion:

  Observed/Correct = 1 + k1*R^2 + k2*R^3

where R is the observed distance in millimeters from the optical center on the sensor.

The executable file includes default values for all parameters affecting the distortion correction, but they can be overridden by placing new values in the file "WAC_Previewer.ini", a copy of which is provided in the present distribution folder. Provided it can be found in the same folder as the program executable, "WAC_Previewer.ini" will be read each time a distortion correction is attempted.  This allows the parameters to be changed interactively without having to have input boxes for them in the main program window.

Although the radial offsets imply that pixels need to be moved both horizontally and vertically, since the framelets are wide but not tall the basic distortion correction consists of making the horizontal corrections only.

==Correct vertically==
This control is visible only when the =Correct distortion= box is checked. When it is checked, a full distortion correction is done, moving the pixels vertically as well as horizontally, giving a curvature to lines that are straight and horizontal in the original.  This introduces a problem which is that the curvature can make it difficult to achieve complete overlap between successive curved framelets.  Areas in which no data can be found to paint the desired image are indicated on the screen by no-data color (default = red, but selectable in "WAC_Previewer.ini").  To overcome this problem, when this box is checked an additional integer input box labeled =Shift= appears.  Entering small positive or negative integers (typically +2 to -2) shifts the vertical starting point at which data is read in the framelets (when Shift=0, reading starts at the upper or lower edge of each band).  A judicious choice of =Shift= will reduce, although it does not always eliminate, the amount of no data area.

==Add to cal file==
Checking this box tells the software to add a line of automatically-generated LTVT calibration data to an LTVT calibration data disk file when you =Save= a stacked image to disk. The calibration data generated in that way allows the saved image to be loaded into and viewed with LTVT. The default destination for the calibration data is a file called "WAC_Images_LTVT_CalibrationData.txt" in the program folder.  If that file does not currently exist, you will be prompted to create it, or, alternatively, you can browse for an existing file to which you wish to append the data, or you can create one of whatever name and at whatever location you choose.  Generating the LTVT calibration record requires use of the support data found in CUMINDEX.TAB. If the support data for the current image has not previously been loaded, the =Support= button will automatically be clicked.  The LTVT record that is generated includes a comment listing the program version and the key parameters used for the stacking.  It is recommended that a development version of LTVT from September 2010 or later be used for displaying these images, since early versions do not handle mirrored satellite images properly.  LTVT data is not generated when =Raw= (unstacked) images are saved.

Note: even with the present attempt to correct the rather severe geometric distortion of the LROC WAC images, the automatic LTVT calibrations produced by this version of the WAC Previewer are rather crude, but they are adequate to load and display most of the images in LTVT and to identify the features being displayed -- although many will be displaced from their expected positions.  Somewhat better calibrations can be produced by manually selecting calibration (reference) points in the central area.

==Clear==
Click this button to erase the contents of the memo box.  It has no effect on the image display, and does not delete the currently loaded data.

==Raw==
Click this button to display the currently loaded IMG data using the current framelet inversion option.

==Invert framelets==
Checking this box tells the software to turn the individual framelets over vertically, which may be necessary to make their orientation match the camera drift direction (framelets are always displayed in the raw data with the first exposure in the time sequence at the top -- but the camera orientation may be inverted relative to the direction of drift over the Moon).  The first framelet in the time sequence will continue to be displayed at the top and the last at the bottom.

==Vertical travel:==
Enter a decimal number representing the assumed amount of vertical displacement between framelets.  This is controlled by the relationship between spacecraft velocity and frame rate.  The LROC documentation indicates the frame rate is adjusted after every 10 degrees of travel or so.  The normal value appears to be close to 11.0 pixels, but any number from 0.0 to 14.0 can be tried.  This number controls the number of lines from each framelet that will be left visible when the =Stack= button is clicked.  Note that for UV bands, the "pixels" in the EDR records correspond to approximately 5.124 times as much distance on the Moon (a combination of a 1.281x times shorter focal length lens and 4x4 binning on the detector), so a typical number for the UV bands is 11/5.124 = 2.15.

==Horizontal travel:==
Enter a decimal number representing the assumed amount of horizontal displacement between framelets.  Again is controlled by the relationship between spacecraft velocity (direction of travel) and frame rate.  The normal value appears to be 0.0 pixels, but any number can be entered, positive or negative. 

==Shift==
An integer input box visible only when the =Correct vertically= option is selected.  See description of that, above, for details.

==Band==
This integer input box is visible whenever multispectral data is being displayed.  Successive integers starting at 1 (and up to maximum of 7 for the "CE" format) are used to select the spectral band to stack, in the order in which they appear in the non-inverted Raw data.  The wavelengths (in nanometers) corresponding to these numbers are displayed in the Memo box when the image is first loaded.
 
==Stack==
Click this button to overlay the Raw framelets of the selected spectral band (either direct or inverted) into a continuous mosaic using the displacements specified by the vertical and horizontal travel controls.  The amount of the first (possibly inverted) framelet (or band) specified by the vertical travel is followed by the same amount from the top of the second and so on until the full final framelet (or band) is added.  The framelets are shifted to the left or right by the amount specified under horizontal travel.  The desired displacement for each framelet is kept track of in floating point, but since it is possible to shift images only by integral numbers of pixels, it is rounded, for each, to the nearest possible integer.

==Save==
Click this button to save the currently displayed image (which may be Raw or Stacked) to disk in BMP format (full color Windows bitmap).  The entire image is always saved, independent of how much of it is visible on the screen. For stacked images, the program will propose a file name incorporating the wavelength of the data that was stacked. You will be prompted if a file of that name already exists in the current directory, but are always free to choose a different name or directory. The saved (and displayed) orientation corresponds to the corner terminology (upper, lower, left, right) used in the support data. Photo processing software can be used to convert the saved image to other formats, such as grayscale BMP or JPG, and to manipulate the intensity levels (the 8-bits of the EDR IMG files match the precision with which the raw data were transmitted to Earth, but the scale is not linear). The image may need to be flipped (mirrored horizontally or vertically) and/or rotated to match the conventional north-up/east-to-right lunar orientation, but do not alter the saved image if you plan to view it with LTVT (the required mirroring code will already be incorporated in the automatically-generated calibration record).


-----------------------
Manipulating the Screen
-----------------------

The images are displayed in a scroll box which can be used to view different parts of them.  The program window itself can be positioned and resized by, for example, dragging the lower right corner with the mouse.  When program window size is changed, the dimensions of the scroll box should increase or decrease with it.

Text information is displayed is displayed in the Memo box at the top of the screen, which for clarity of display has been set to *not* wrap the text when the lines are too long to display.  If you wish to see the ends of lines that are not visible, place the cursor in the line and press the End button on your keyboard.


-------------------------------
Displaying Saved Images in LTVT
-------------------------------

Assuming you have used the =Save= button to write a stacked image to disk with the "Add to cal file" option checked, support data for that image will have been written to an LTVT "cal file" (by default "WAC_Images_LTVT_CalibrationData.txt" in the WAC_Previewer program folder, but you may have selected a different destination).  

To view this image with LTVT you must first download and "install" (unzip) the LTVT software (hopefully a development version from September 2010 or later), and start the program.  Under the "Files" menu, you want to select "Load a calibrated photo...".  You will then see the "Calibrated Photo Selector" window. Click the "Change" button in the upper left of that screen to specify the text file containing the calibration data for your WAC images, then click the "List photos" button with none of the option buttons clicked.  You should see a list of the calibrated images in the order in which they were saved.  Clicking on any of the image names with the mouse will display a thumbnail of it and list the support data under that, including the pixel locations that were used for the "calibration" (currently the upper left and lower right corners of the stacked image, to which the values listed in "CUMINDEX.TAB" were assigned). 

When you have highlighted the image you want to view, check the "Display at original scale and orientation" radio button at the bottom of the screen, and then click the "Select" button. The calibrated image will then have been assigned as one of the current "Textures" and display in the LTVT main window. The date and time of the midpoint of the WAC data scan will also appear in the input boxes at the top of the LTVT screen, but the "Geometry" will be manually set to approximate the LRO viewpoint.  This function does not work perfectly for satellite photos, particularly as to scaling, so you will probably want to adjust the "Zoom" input to a larger value (say 10) and click the "Texture" button to refresh the image.

You can then use any of the normal LTVT buttons (clicking to re-center, "Overlay dots" and "Label" to identify features, etc., and right-clicking for still more options).

If the location you have specified for the calibration data text file is different from the one that was in effect when you started LTVT, then on exiting the program you will be asked if you want to save the new options as your default.  Choose "yes" if you want LTVT to automatically use the same calibration data file the next time you start the program.  You can also make this change from the LTVT Main Screen by selecting "Files...Change external file associations..." and using the "Calibrated Photos" button to modify the selection.  Click "Save as Default" if you want the change to be permanent. 


----------
References
----------

Professional articles:
  
1. Anderson, 2009 : http://adsabs.harvard.edu//abs/2009LPI....40.1905A  (general description of "pushframe" formats)

2. Bowman-Cisneros, 2009 : http://pds-imaging.jpl.nasa.gov/documentation/LRO_DPSIS.PDF (PDS summary of WAC instrument and data formats)

3. Bowman-Cisneros, 2010 : http://lroc.sese.asu.edu/data/LRO-L-LROC-2-EDR-V1.0/LROLRC_0001/DOCUMENT/LROCSIS.PDF (PDS summary of WAC instrument and data formats)

4. Robinson, 2010 : http://adsabs.harvard.edu/abs/2010SSRv..150...81R (definitive description of construction, calibration and operation of the WAC)


Amateur attempts to re-assemble WAC images:

1. John Moore LPOD: http://lpod.wikispaces.com/August+29,+2010
2. Rick Evans LPOD: http://lpod.wikispaces.com/September+1%2C+2010
3. Maurice Collins LPOD: http://lpod.wikispaces.com/September+4%2C+2010


-----------
Source Code
-----------

The zipped distribution file includes a subfolder labeled "Delphi Source Code".  Within it are most of the files from which the Windows executable are generated.  Delphi 6 is a "Rapid Application Development" compiler that was once distributed for free.  See:

http://en.wikipedia.org/wiki/Embarcadero_Delphi

The Pascal instructions for doing the stacking are in the file "WAC_Previewer_Unit.pas" but they call other "units" which can be found in the LTVT source code.  The remaining files in the "Delphi Source Code" define the graphic interface (the locations of "controls" on the Windows screen) and compiler options.  They may or may not be compatible with more recent versions of Delphi.


--------------------
Contact/Distribution
--------------------

The present program was written by Jim Mosher (jimmosher@yahoo.com). 

The executable and source code are freely available on the LTVT website at: 

  http://ltvt.wikispaces.com/Utility+Programs#WAC_Viewer

The LTVT program can be found on the same site.





